home *** CD-ROM | disk | FTP | other *** search
/ Aminet 19 / Aminet 19 (1997)(GTI - Schatztruhe)[!][Jun 1997].iso / Aminet / dev / misc / prog_bar_12.lha / prog_bar / Docs / readme.txt < prev   
Encoding:
Text File  |  1997-03-04  |  14.8 KB  |  418 lines

  1.  
  2.                                 Prog_Bar.Lib
  3.                                 ============
  4.  
  5.              A progress bar link library for Amiga Programmers
  6.              =================================================
  7.  
  8.                        Written by Allan Savage © 1996
  9.                        ==============================
  10.  
  11.  
  12. Introduction
  13. ============
  14.  
  15. Prog_Bar.lib  is  a  progress  bar  link library designed to make it easy to
  16. create,  manage  and delete progress bars within most programming languages.
  17. It  has  been  tested  using  Dice  C,  Devpac  3  Assember, SAS/C and Turbo
  18. Modula-2.
  19.  
  20. The  library  is  easy to use and provides a large range of options for your
  21. progress  bars.   It  has  been  designed to operate in a similar way to the
  22. GadTools functions for managing gadgets, so the ideas involved should not be
  23. new to anyone who might be using them.
  24.  
  25. The  library  is  capable of producing many different types of progress bars
  26. using  a simple set of parameters.  These allow the programmer to completely
  27. customise  a  progress  bar by changing its border, colours, size, location,
  28. dimensions, direction and text.
  29.  
  30. To  give you an idea of what is possible using this system I have included a
  31. few  demonstration  programs complete with source code so that you can learn
  32. from the techniques used to control a progress bar.
  33.  
  34.  
  35.  
  36. Installation
  37. ============
  38.  
  39. How  to  install and use the library really depends on which environment you
  40. want  to  use it in.  I will provide a general outline of the various stages
  41. and  a more detailed description of how I installed it with each system.  In
  42. each case you may be using a different system, but if you follow the general
  43. guidelines you should not have much difficulty.
  44.  
  45. I  will  also show the commands I used to compile and link the demo programs
  46. for each system.
  47.  
  48. The  documentation includes an Amigaguide file called prog_bar.guide .  This
  49. contains  a  detailed description of each function and can be copied to your
  50. compiler's   document   directory,  or  can  be  linked  into  the  Autodocs
  51. documentation  if  you have it installed.  A plain text version of this file
  52. is also supplied.  It is called "prog_bar.doc".
  53.  
  54.  
  55. C Installation
  56. --------------
  57.  
  58. The C system is comprised of two files, "prog_bar.h" and "prog_bar.lib".
  59.  
  60. "prog_bar.h"  should  be  copied to anywhere on your compiler's include file
  61. search path.  Just make sure you know where you put it because you will need
  62. to #include it any time you want to use prog_bar.
  63.  
  64. For  Dice  I  created a directory called "DINCLUDE:library" and copied it to
  65. there.
  66.  
  67. "prog_bar.lib"  should  be  copied  to  anywhere  on your compiler's library
  68. search  path.   Alternatively you could put it anywhere and then specify its
  69. full pathname when linking.
  70.  
  71. In Dice I copied it to "DCC:dlib/"
  72.  
  73.  
  74. Assembler Installation
  75. ----------------------
  76.  
  77. The   Assembler   system   is  comprised  of  two  files,  "prog_bar.i"  and
  78. "prog_bar.lib".
  79.  
  80. "prog_bar.i"  should  be copied to anywhere on your assembler's include file
  81. search path.  Just make sure you know where you put it because you will need
  82. to include it any time you want to use prog_bar.
  83.  
  84. For Devpac I copied it to the "Devpac/include/libraries" directory.
  85.  
  86. "prog_bar.lib"  should  be  copied  to  anywhere on your assembler's library
  87. search  path.   Alternatively you could put it anywhere and then specify its
  88. full pathname when linking.
  89.  
  90. In Devpac I copied it to "Devpac/lib/"
  91.  
  92.  
  93. Modula-2 Installation
  94. ---------------------
  95.  
  96. The   Modula-2   system   is   comprised  of  three  files,  "prog_bar.def",
  97. "prog_bar.sym" and "prog_bar.lib".
  98.  
  99. "prog_bar.def"  should be copied to anywhere on your compiler's include file
  100. search path.  Just make sure you know where you put it because you will need
  101. to import it any time you want to use prog_bar.
  102.  
  103. For Turbo Modula-2 I copied it into the "Modula_2/amiga/" directory.
  104.  
  105. "prog_bar.sym"  should  be  copied to your compiler's symbol file directory.
  106. If  the  "prog_bar.sym"  file is not of the correct format for your compiler
  107. you will need to recreate it.  This is done by compiling "prog_bar.def".
  108.  
  109. For Turbo Modula-2 I copied it into the "Modula_2/sym/" directory.
  110.  
  111. "prog_bar.lib"  should  be  copied  to  anywhere  on your compiler's library
  112. search  path.   Alternatively you could put it anywhere and then specify its
  113. full pathname when linking.
  114.  
  115. For Turbo Modula-2 I copied it into the "Modula_2/lib/" directory.
  116.  
  117.  
  118. N.B.   I  have  my  copy  of  Turbo  Modula-2  installed  in  the "Modula_2"
  119. directory.
  120.  
  121.  
  122.  
  123. Usage
  124. =====
  125.  
  126. General Description
  127. -------------------
  128.  
  129. Using  the  system  should  now  be  (almost)  as simple as using any of the
  130. operating system libraries.  When you write a program which needs a progress
  131. bar  just include the relevant definition file at the top of your source and
  132. remember to link your object file to prog_bar.lib.
  133.  
  134. The  only  other requirements are that the Intuition, Gadtools, Graphics and
  135. Utility  libraries  are  opened by your program.
  136.  
  137. To  actually  create  and handle a progress bar within your program you will
  138. need  to  follow  the  rough guide given below.  However, every situation is
  139. different  so  you  might  need  to  vary  your approach.  All the available
  140. functions are documented in the function list.
  141.  
  142. N.B.   Because all of the necessary functions will be linked into your final
  143. executable it is completely unnecessary to open the library at runtime.
  144.  
  145.  
  146. Step 1.
  147.  
  148. Work  out  what  size  your  bar has to be.  Note that the size is the value
  149. represented  by  the  full  bar.   It  is  not  related  to the bar's actual
  150. dimensions.
  151.  
  152. How you do this will depend on what you are using the bar for.  For example,
  153. if  you want to represent a percentage the size would be 100.  If you wanted
  154. to  use  a progress bar while printing the size might be the number of lines
  155. to be printed.
  156.  
  157.  
  158. Step 2.
  159.  
  160. Create a suitable progress bar using CreateProgBarA() or CreateProgBar() .
  161.  
  162.  
  163. Step 3.
  164.  
  165. Every  time  your  program  completes  one unit of whatever it is doing, you
  166. should  use  UpdateProgBar()  to display the new position.  For the examples
  167. above  this would mean updating the bar after one percent, or after printing
  168. each line.
  169.  
  170. If  the  value  of  the  bar  is  decreasing  and you have the text function
  171. activated,  it  will  probably  be necessary to call ClearText() immediately
  172. before  updating  the  bar.   This  is  not necessary if the text is centred
  173. within the bar, or if the length of the text never decreases.
  174.  
  175.  
  176. Step 4.
  177.  
  178. When  you  have  finished you should delete the progress bar and release the
  179. memory used by calling FreeProgBar() .
  180.  
  181.  
  182. Step 5.
  183.  
  184. When your window needs refreshed you should call RefreshProgBar() .
  185.  
  186.  
  187. Using Prog_Bar in C
  188. -------------------
  189.  
  190. When  writing  your  source  you  will need to include the file "prog_bar.h"
  191. before  you  use  any of the functions, otherwise the compiler will complain
  192. about undefined structures, etc.
  193.  
  194. In Dice I use the line "#include <library/prog_bar.h>".
  195.  
  196. When  compiling  you will then need to tell the compiler to include the code
  197. for  the  prog_bar  functions.   This  is  done  by  linking  your  code  to
  198. "prog_bar.lib".   In some compilers, or with large multi-module programs, it
  199. will  be  necessary to compile your source to *.o files, and then link these
  200. and  prog_bar.lib  together to produce the executable.  If your program is a
  201. single  source  file  then  you  might  be  able  to  compile it and link to
  202. prog_bar.lib  in  one instruction.  Your compiler documentation will contain
  203. more detailed information about this.
  204.  
  205. To  compile  the demo with Dice I was able to compile the source and perform
  206. the  link  in  one operation.  The command line to do this was "dcc -2.0 -//
  207. -Tt: -o Demo Demo.c prog_bar.lib".
  208.  
  209.  
  210. Calling the prog_bar functions uses exactly the same notation as any other C
  211. function, e.g.  "ClearProgBar(PBar);".
  212.  
  213.  
  214. Using Prog_Bar in Assembler
  215. ---------------------------
  216.  
  217. When  writing  your  source  you  will need to include the file "prog_bar.i"
  218. before  you  use any of the functions, otherwise the assembler will complain
  219. about undefined symbols, etc.
  220.  
  221. In Devpac I use the line "include libraries/prog_bar.i".
  222.  
  223. To  produce your final executable you will need to assemble your source as a
  224. linkable  file.   The  resulting  *.o  file will then need to be linked with
  225. Prog_Bar.lib.
  226.  
  227. To  create  the  demo program with Devpac I created my source in a directory
  228. called  "Devpac/Progs".   From  here  the command to link the executable was
  229. "BLINK demo.o TO demo LIB /lib/prog_bar.lib".
  230.  
  231. Your  assembler  documentation  will contain more detailed information about
  232. assembling and linking programs.
  233.  
  234.  
  235. Calling  the prog_bar functions can be done in one of two ways (at least for
  236. most  of  them),  namely  stack based, and register based parameter passing.
  237. All  the functions can be used with the stack based method, and most of them
  238. can  be  used  with  the register based method.  If register based parameter
  239. passing  is  supported by a function, the  function list will tell you which
  240. registers are used.
  241.  
  242.  
  243. To  call a prog_bar function using the stack based method you must place its
  244. parameters  on  the  stack  in the reverse order, i.e.  right to left.  Each
  245. value you place on the stack MUST be a longword value, even if the parameter
  246. type is a word or byte value.
  247.  
  248. To actually call the function you just use a JSR instruction.  The target of
  249. the  jump will be the function name preceded by an underscore, e.g.  to call
  250. CreateProgBar() you use the instruction "JSR _CreateProgBar".
  251.  
  252. When  the  function  returns you are responsible for removing its parameters
  253. from the stack.  Any return values will be in the register D0.
  254.  
  255.  
  256. To  call  a  function  using  the register based method you simply place its
  257. parameters in the relevant processor registers and call the function using a
  258. JSR instruction.  This time the target of the jump will be the function name
  259. preceded  by  an  "@"  symbol,  e.g.   to  call UpdateProgBar()  you use the
  260. instruction  "JSR  @UpdateProgBar".   Again  any  return  values  will be in
  261. register D0.
  262.  
  263.  
  264. An  example  demonstrating  the difference is this small piece of code which
  265. calls UpdateProgBar() using both methods.
  266.  
  267.  
  268.             UpdateProgBar ( PBar_Ptr, Value )
  269.  
  270.  
  271.             * Stack Based
  272.             move.l   Value,-(sp)       ;  Place Value on Stack
  273.             move.l   PBar_Ptr,-(sp)    ;  Place PBar_Ptr on Stack
  274.             jsr      _UpdateProgBar    ;  Call UpdateProgBar()
  275.             lea      8(sp),sp          ;  remove parameters from stack
  276.                                        ;  2 parameters * 4 bytes each = 8
  277.  
  278.             * Register Based
  279.             move.l   PBar_Ptr,A0       ;  Place PBar_Ptr in A0
  280.             move.l   Value,D0          ;  Place Value in D0
  281.             jsr      @UpdateProgBar    ;  Call UpdateProgBar()
  282.  
  283.  
  284.             Value       dc.l     50
  285.             PBar_Ptr    dc.l     0
  286.  
  287.  
  288. Using Prog_Bar in Modula-2
  289. --------------------------
  290.  
  291. When  writing  your  source  you will need to import the file "prog_bar.def"
  292. before  you  use  any of the functions, otherwise the compiler will complain
  293. about undefined structures, etc.
  294.  
  295. In Turbo Modula-2 I use the line "IMPORT P := prog_bar".
  296.  
  297. When  compiling  you will then need to tell the compiler to include the code
  298. for  the  prog_bar  functions.   This  is  done  by  linking  your  code  to
  299. "prog_bar.lib".   Your  compiler  documentation  will  contain more detailed
  300. information about this.
  301.  
  302. To  compile  the demo with Turbo Modula-2 I just added "prog_bar.lib" to the
  303. end  of  my compile command.  The resulting command line to achieve this was
  304. "m2b Demo prog_bar.lib".
  305.  
  306.  
  307. Calling  the  prog_bar functions uses exactly the same notation as any other
  308. Modula-2 function, e.g.  "P.ClearProgBar(PBar);".
  309.  
  310.  
  311.  
  312. Demonstration Programs
  313. ======================
  314.  
  315. The Library can currently be used from Modula-2, C and Assembly Language.  I
  316. have  included  small example programs in each language so that you can test
  317. the library with your compiler before writing anything of your own.
  318.  
  319.  
  320. All Programmers
  321. ---------------
  322.  
  323. The demo program written in C is by far the largest of the demo programs.  C
  324. is  my preferred language so I used this program as a complete demonstration
  325. of  everything  the library can do.  As such it is probably worth looking at
  326. even if you do not normally program in C.
  327.  
  328.  
  329. Assembly Programmers
  330. --------------------
  331.  
  332. This  is  a small program which creates a progress bar and then slowly fills
  333. it.  When full, the bar is reset and the process repeats.  Just click on the
  334. Window's Close gadget to end the program.
  335.  
  336.  
  337. Modula-2 Programmers
  338. --------------------
  339.  
  340. This  is  also a small program.  It fills a progress bar in steps of 1, then
  341. changes  the  direction,  border and text mode of the bar, and then fills it
  342. again in steps of 5.  You just have to wait until it has finished.
  343.  
  344.  
  345.  
  346. Distribution
  347. ============
  348.  
  349. Prog_Bar is Copyright © Allan Savage 1996.  All Rights Reserved.
  350.  
  351. Prog_Bar  is freely distributable, providing that no commercial gain is made
  352. from its distribution, and no modification is made to the original archive.
  353.  
  354. Anyone  wishing to include Prog_Bar on a magazine coverdisk or other similar
  355. collection,  or  use it in any application, commercial or otherwise, have my
  356. full permission.  All I ask in return is to be acknowledged somewhere in the
  357. documentation and to be told about it (preferably by e-mail).
  358.  
  359.  
  360.  
  361. Disclaimer
  362. ==========
  363.  
  364. This  software  is  provided  "AS  IS"  without warranty of any kind, either
  365. expressed  or implied, including, but not limited to, the implied warranties
  366. of  merchantability  and  fitness for a particular purpose.  The author does
  367. not guarantee the use of, or the results of the use of, this software in any
  368. way.   In  no  way  will  the  author  be  held liable for direct, indirect,
  369. incidental, or consequential damages to data or equipment resulting from the
  370. use of this software.
  371.  
  372.  
  373.  
  374. Acknowledgements
  375. ================
  376.  
  377. The  Demonstration  program  was  compiled  using  DICE  v2.07.56  R and its
  378. interface  was designed using GadToolsBox v37.300.  Thanks to Matthew Dillon
  379. and Jan van den Baard for these excellant programs.
  380.  
  381. Many  thanks also to Roberto Bizzarri for his assistance in testing Prog_Bar
  382. v1.1 with SAS/C.
  383.  
  384.  
  385.  
  386. How to contact me
  387. =================
  388.  
  389. If  you  have  any  suggestions  for  improving  Prog_Bar, bugs to report or
  390. queries  about  the  program, please send them to me at one of the addresses
  391. below.
  392.  
  393.         E-Mail :  asavage@bitsmart.com         (preferred option)
  394.                   asavage@enterprise.net
  395.  
  396.         Post   :  Mr. Allan Savage
  397.                   2 Navar Drive
  398.                   Gransha Road
  399.                   Bangor
  400.                   N. Ireland
  401.                   BT19 7SW
  402.  
  403.  
  404.  
  405. Program History
  406. ===============
  407.  
  408. V1.0   13/12/96   - Initial Release.  (Only worked with Dice)
  409.  
  410. V1.1   11/01/97   - Rewritten  in  Assembly  language.   Now  works with all
  411.                     compilers (hopefully).
  412.                   - Added definiton files for Assembler and Modula-2.
  413.                   - Added Demo programs for Assembler and Modula-2.
  414.  
  415. V1.2   03/03/97   - Removed the need to link with amiga.lib.
  416.                   - Added support for registerised argument passing.
  417.  
  418.